home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / doors_1 / easydoor.zip / EASYDOOR.DOC < prev    next >
Text File  |  1993-03-01  |  20KB  |  550 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                       Easy-Door V1.0 library for Quick-Basic 4.5
  11.  
  12.                                   by Martin Bouchard,
  13.                                      1207 du Golf
  14.                                    Cap-Rouge, Quebec
  15.                                         Canada
  16.                                         G1Y 2T4
  17.  
  18.  
  19.             Easy-Door is  a library that provides a convenient and easy way
  20.             to program your own doors with Microsoft Quick Basic.
  21.  
  22.             Doors  programmed  with  the  Easy-Door  library  are  QuickBBS
  23.             compatible doors.
  24.  
  25.             Features of the Easy-Door library:
  26.  
  27.                          - Fast modem input/output
  28.                          - Uses of the X00 fossil driver (C) Ray Gwinn
  29.                          - Menu with programmables HOT KEYS like QuickBBS
  30.                          - ANSI graphic sequence support
  31.                          - Modem and keyboard/screen controls
  32.                          - Automatic status bar with user's informations
  33.                          - Automatic carrier detection
  34.                          - Automatic time left verification
  35.                          - Inactivity timeout verification
  36.                          - Useful file sender with pause and stop option
  37.                          - And a lot more!
  38.  
  39.             Requirements:
  40.  
  41.                          - Quick Basic 4.5
  42.                          - X00.SYS (fossil driver) See next page for info.
  43.                          - ANSI.SYS driver (only if you want ANSI graphics)
  44.                          - Easy-Door library
  45.  
  46.  
  47.             Note: 
  48.  
  49.                The  X00.SYS driver  is not  included with  Easy-Door. Thus,
  50.             this driver  can be  found on severals  BBS. When you  register
  51.             Easy-Door, the disk enclosed will contain the X00 fossil driver
  52.             and the registred Easy-Door library.
  53.  
  54.  
  55.  
  56.                            Easy-Door library for Quick Basic
  57.                              Copyright (C) Martin Bouchard
  58.  
  59.  
  60.  
  61.  
  62.  
  63.             Copying and Distribution:
  64.  
  65.                Easy-Door  may  be  copied and  distributed  freely.  If you
  66.             dristibute Easy-Door on  communications systems such as  BBS or
  67.             CompuServe,  The  Source,  Genie,  etc,  you  must  include the
  68.             following files as  a set (using  ARC, ZIP, LZH, PAK,  etc.) No
  69.             fee other than a disk and handling charge (of up to 8$) may  be
  70.             charged. The Easy-Door library is copyright and no modification
  71.             may be made to the library.
  72.  
  73.  
  74.             Caveats:
  75.  
  76.                These routines have not caused me any problems,  and seem to
  77.             be  fully debuged. However, I  will not be  responsible for any
  78.             damages caused by use, misuse, or inability to use Easy-Door.
  79.  
  80.  
  81.             Description of files:
  82.  
  83.                     - EASYDOOR.DOC  (Easy-Door documentation)
  84.                     - EASYDOOR.LIB  (Easy-Door module for compiling)
  85.                     - EASYDOOR.QLB  (Easy-Door module for QB environement)
  86.                     - EASYDEMO.BAS  (Sample demo for getting started)
  87.                     - REGISTER.DOC  (Registration form)
  88.                     - LOCAL.DEF     (Data file with user info.)
  89.  
  90.             Description of a door:
  91.  
  92.                A door is an external program that works in conjunction with
  93.             a Bulletin Board  System (BBS). Doors are  difficult to program
  94.             because they have to use the modem  input/output commands, ANSI
  95.             character display, carrier detection, inactivity time out, time
  96.             left,  hot keys, status bar,  etc. So that's  what Easy-Door is
  97.             for.  It's a sample way  to program doors  with minimal efforts
  98.             and programming time.
  99.  
  100.  
  101.             Fossil driver:
  102.  
  103.                A fossil driver is a program that controls different things.
  104.             X00.sys is a communication driver (X00.sys is copyright by  Ray
  105.             Gwinn). Every QuickBBS  system needs  it's own  X00.sys driver.
  106.             So, you don't have to distribute  the X00.sys driver with  your
  107.             door program.
  108.  
  109.  
  110.  
  111.                            Easy-Door library for Quick Basic
  112.                              Copyright (C) Martin Bouchard
  113.  
  114.  
  115.  
  116.  
  117.  
  118.             Registration:
  119.  
  120.                The Easy-Door library is NOT  public domain, it's SHAREWARE.
  121.             It means  that you have to  pay registration fees (25$)  if you
  122.             use the Easy-Door  library in  your programs.  The registration
  123.             cost is minimal  and will  allow the  author to  write new  and
  124.             improved versions of  the Easy-Door  library. Please  note that
  125.             the unregistered version is  the same as the registered version
  126.             except  that a special screen  is displayed each  time an Easy-
  127.             Door program  is  run. Registered  users will  receive  a  disk
  128.             containing  the  Easy-Door library  and  the X00  communication
  129.             fossil driver (Copyright Ray Gwinn).
  130.  
  131.  
  132.             *** Last minute note: ***
  133.  
  134.                Easy-Door V1.1 is  now available if you  register your Easy-
  135.             Door. New routines  are ANSI locate, sound,  optional automatic
  136.             reboot after lost of carrier, send function with colors, etc.
  137.  
  138.  
  139.             How to install Easy-Door?
  140.  
  141.             To install Easy-Door follow these steps:
  142.  
  143.                     - Copy EASYDOOR.LIB and EASYDOOR.QLB in the directory
  144.                       where you put your library files (Ex. BCOM45.LIB)
  145.  
  146.                     - Copy LOCAL.DEF in the directory where you put your
  147.                       .BAS files.
  148.  
  149.                     - Install X00.SYS in your CONFIG.SYS (see your X00.SYS
  150.                        documentation)
  151.  
  152.                     - Start Quick Basic with the following syntax:
  153.                       QB /l EasyDoor
  154.  
  155.  
  156.  
  157.                            Easy-Door library for Quick Basic
  158.                              Copyright (C) Martin Bouchard
  159.  
  160.  
  161.  
  162.  
  163.  
  164.             How to use Easy-Door library routines?
  165.  
  166.                To use  the Easy-Door  library, you  must first  load Quick-
  167.             Basic with the (QB /l EasyDoor) statement. Each routine must me
  168.             CALLed:
  169.  
  170.             Ex.   CALL Init ' Initialize Easy-Door
  171.                   CALL ModemInput ("Your firstname? ", firstname$, 30)
  172.  
  173.                Every Easy-Door variables  are strings or integer.  So, when
  174.             you use numeric variable put the % sign after the variable name
  175.             or put a DEFINT A-Z at the beginning of your program.
  176.  
  177.  
  178.  
  179.                            Easy-Door library for Quick Basic
  180.                              Copyright (C) Martin Bouchard
  181.  
  182.  
  183.  
  184.  
  185.  
  186.             Technical information about Easy-Door.
  187.  
  188.                Easy-Door provides an  easy alternative to program  your own
  189.             door  easily.  You  don't  have   to  care  about  opening  the
  190.             communication port.  Easy-Door, will automatically  get wich of
  191.             the serial port is in use by the BBS. 
  192.  
  193.                To access  the communication  port, Easy-Door  uses the  X00
  194.             fossil  driver (Copyright  Ray  Gwinn). Consequently,  you  can
  195.             access  the communication  port at  high rate.  To obtain  ANSI
  196.             graphic, you  must install  the ANSI.SYS  or compatible  driver
  197.             (ZANSI, NNANSI,  etc.) in your  CONFIG.SYS if  it's not already
  198.             installed.
  199.  
  200.  
  201.                Each  time an Easy-Door command  is made, Easy-Door check if
  202.             the user has disconnected (if there's a lost of carrier). Also,
  203.             Easy-Door check the timelimit of the user and for an inactivity
  204.             time out (after 2 minutes of inactivity, Easy-Door will hang up
  205.             the line and will return to the BBS).
  206.  
  207.                A very useful option of  Easy-Door is hot keys. Hot keys are
  208.             keys that the user can press during the transmission of a menu.
  209.             So,  the  user  doesn't  have  to  wait  at  the   end  of  the
  210.             transmission to press the key of  his desired option. Hot  keys
  211.             are difficult  to program, but with  the Easy-Door library it's
  212.             just fun to use.
  213.  
  214.                User  informations are read in a file that QuickBBS produces
  215.             every time a door is run. This file is DORINFO1.DEF. But if you
  216.             don't run the door from a BBS, Easy-Door will read a file named
  217.             LOCAL.DEF.
  218.  
  219.             The contents of DORINFO1.DEF or LOCAL.DEF is the following
  220.  
  221.                     DELTA-BBS           (Name of the BBS)
  222.                     MARTIN              (SysOp's fistname)
  223.                     BOUCHARD            (SysOp's lastname)
  224.                     COM1                (COM port number, COM0 = local use)
  225.                     0                   (Nothing, just a 0)
  226.                     DAVE                (User's firstname)
  227.                     SMITH               (User's lastname)
  228.                     DAYTONNA, FL        (User's city)
  229.                     1                   (1=ANSI 0=ASCII)
  230.                     40                  (Security level)
  231.                     24                  (Time remaining in minutes)
  232.  
  233.                These informations are  only for technical purposes,  so you
  234.             don't need to access those files.
  235.  
  236.  
  237.  
  238.                            Easy-Door library for Quick Basic
  239.                              Copyright (C) Martin Bouchard
  240.  
  241.  
  242.  
  243.  
  244.  
  245.             CenterBox (TextLine1$, TextLine2$) 
  246.  
  247.                     Displays a window in the center of the  screen with two
  248.                     lines of centered text  inside it. This window  is only
  249.                     seen on the host screen.
  250.  
  251.                     Example:
  252.  
  253.                     CALL CenterBox ("Text line# 1", "Text line #2") 
  254.  
  255.  
  256.  
  257.             ChangeDTR (DTR%) 
  258.  
  259.                     Change the  Data Terminal  Ready  (DTR) status  on  the
  260.                     current serial port. A value of one will raise the DTR,
  261.                     and a zero will lower it. On most  modems, lowering the
  262.                     DTR will force the modem to hang up.
  263.  
  264.                     Example:
  265.  
  266.                     CALL ChangeDTR (0) ' Put the DTR low
  267.                     CALL ChangeDTR (1) ' Put the DTR high
  268.  
  269.  
  270.             CheckCD
  271.              
  272.                      Forces  Easy-Door  to  check if  there  is a  lost  of
  273.                     carrier on  the current  serial  port. If  there is  no
  274.                     carrier, the program will be terminated and will return
  275.                     to DOS (returning control to  QuickBBS when the door is
  276.                     installed  on a BBS). This routine  is not usually used
  277.                     because   Easy-Door   performs  an   automatic  carrier
  278.                     detection each time inputs/outputs are made. But it can
  279.                     be uses  if no modem  input/output is  made for a  long
  280.                     time (like sorting a string array)
  281.  
  282.                     Example:
  283.  
  284.                     CALL CheckCD ' Force Easy-Door to check for carrier
  285.  
  286.  
  287.             GetChar (Char$)
  288.  
  289.                     Returns  either  a  one-character string  containing  a
  290.                     character read from the modem/keyboard buffer or a null
  291.                     string ("") if  no character is pending.  This routines
  292.                     is like  the Quick  Basic  INKEY$ statement  but  reads
  293.                     character from the modem and the keyboard.
  294.  
  295.  
  296.  
  297.                            Easy-Door library for Quick Basic
  298.                              Copyright (C) Martin Bouchard
  299.  
  300.  
  301.  
  302.  
  303.  
  304.             HangUp
  305.  
  306.                     Disconnects the user by hanging up the line.
  307.  
  308.                     Example:
  309.  
  310.                     CALL HangUp ' Disconnect the user online
  311.  
  312.  
  313.             Init
  314.  
  315.                     This routine is the  most important of all. It performs
  316.                     initialization to the modem, read the user informations
  317.                     and  a lot  more.  You must  call  this routine  before
  318.                     calling any other Easy-Door routines. If you omit to do
  319.                     this, your program will not work.
  320.  
  321.                     Example:
  322.  
  323.                     CALL Init ' Initialize Easy-Door ** Very important **
  324.  
  325.  
  326.             Linefeed (NumberOfLinefeed%)
  327.  
  328.                     Send  one or  more linefeeds  (change  of line)  to the
  329.                     modem and to the screen.
  330.  
  331.                     Example:
  332.  
  333.                     CALL linefeed(3) ' Send 3 linefeeds
  334.  
  335.  
  336.  
  337.                            Easy-Door library for Quick Basic
  338.                              Copyright (C) Martin Bouchard
  339.  
  340.  
  341.  
  342.  
  343.  
  344.             MiscInfo (InfoNumber%, Info$)
  345.  
  346.                     Returns miscellaneous informations. You give the number
  347.                     of the information you want and Easy-Door returns it in
  348.                     a string variable.
  349.  
  350.                     Information #       Contents
  351.  
  352.                          1              User's firstname
  353.                          2              User's lastname
  354.                          3              User's city
  355.                          4              1=ANSI 0=ASCII
  356.                          5              User's security
  357.                          6              Remaining  time  when  user entered
  358.                                         the door (min.)
  359.                          7              Communication  port  in   use  (Ex.
  360.                                         COM2)
  361.                          8              Communication    parameters    (Ex.
  362.                                         1200,N,8,1)
  363.                          9              Sysop's firstname
  364.                          10             Sysop's lastname
  365.                          11             BBS's name
  366.  
  367.                     Example:
  368.  
  369.                     CALL MiscInfo (1, Firstname$)
  370.                     CALL SendCR ("Welcome " + Firstname$)
  371.  
  372.  
  373.             ModemInput (Prompt$, Answer$, MaxLen%)
  374.  
  375.                     Inputs a  string from the  modem or  the keyboard.  You
  376.                     have  to specify the  maximum length of  the string. If
  377.                     you do not want a prompt, use a null string ("").
  378.  
  379.                     Example:
  380.  
  381.                     CALL ModemInput ("Your name: ", Name$, 25) ' Ask the   
  382.                     name of the user with no more then 25 characters. 
  383.  
  384.  
  385.  
  386.                            Easy-Door library for Quick Basic
  387.                              Copyright (C) Martin Bouchard
  388.  
  389.  
  390.  
  391.  
  392.  
  393.             ModemInputChar (Char$)
  394.  
  395.                     Inputs a character from the modem or the keyboard. This
  396.                     routine will wait for one  character and return control
  397.                     to the program after.
  398.  
  399.                     Example:
  400.  
  401.                     CALL ModemInputChar (K$)
  402.                     PRINT "You pressed the "+k$+" key."
  403.  
  404.  
  405.             ModemOnlySend (String$)
  406.  
  407.                     Sends a string of characters only to the  modem, not to
  408.                     the screen.
  409.  
  410.  
  411.             PurgeInBuffer
  412.  
  413.                     Clears all the pending  characters in the modem and the
  414.                     keyboard input buffer.
  415.  
  416.  
  417.             PurgeOutBuffer
  418.  
  419.                     Clears all  the characters  in  the output  buffer  not
  420.                     already transmitted.
  421.  
  422.  
  423.             ReturnBBS
  424.  
  425.                     You must use this routine  to return to the BBS. DO NOT
  426.                     USE the END statement. Also,  this routine will display
  427.                     a window that will announce the return to the BBS.
  428.  
  429.                     Example:
  430.  
  431.                     CALL ReturnBBS ' Exit the DOOR and return to the BBS.
  432.  
  433.  
  434.             Send (String$)
  435.  
  436.                     Sends  a string of characters  to the modem  and to the
  437.                     screen.
  438.  
  439.                     Example:
  440.  
  441.                     CALL Send ("Welcome to this door!")
  442.  
  443.  
  444.  
  445.                            Easy-Door library for Quick Basic
  446.                              Copyright (C) Martin Bouchard
  447.  
  448.  
  449.  
  450.  
  451.  
  452.             SendCLS
  453.  
  454.                     Sends a clear screen code (ASCII CODE 12).
  455.  
  456.  
  457.             SendCR (String$)
  458.  
  459.                     Same as the Send routine except  a linefeed is sent  at
  460.                     the end of the line.
  461.  
  462.  
  463.             SendFile (Filename$, Option%)
  464.  
  465.                     Sends  a   file  for   viewing  purpose.   During   the
  466.                     transmission,  the user  can  press keys  (P and  S) to
  467.                     pause or stop viewing the file.
  468.  
  469.                     Option% = 0   (Enables the user to stop and pause the
  470.                                    display)
  471.  
  472.                     Option% = 1   (Enables the user to only pause the
  473.                                    display, the user can't stop the
  474.                                    display.)
  475.  
  476.                     Example:
  477.  
  478.                     CALL SendFile ("EasyDoor.doc", 0)
  479.  
  480.  
  481.             SendMenu (Menuname$, HotkeysList$, Keypress$)
  482.  
  483.                     Sends a menu  file. During  the transmission, the  user
  484.                     may press  a key  in the hot  keys list. The  menu name
  485.                     must be a  filename with  no extension. Easy-Door  will
  486.                     add .ASC or .ANS to the file name depending if the user
  487.                     has ASCII or ANSI graphics.
  488.  
  489.                     Example:
  490.  
  491.                     CALL SendMenu("Menu", "DUQ", k$) ' Transmit the
  492.                                                        Menu.ASC or Menu.ANS
  493.                                                        file  and  wait  for
  494.                                                        D,U or Q key.
  495.  
  496.  
  497.  
  498.                            Easy-Door library for Quick Basic
  499.                              Copyright (C) Martin Bouchard
  500.  
  501.  
  502.  
  503.  
  504.  
  505.             SendString (String$, HotkeysList$, Keypress$) 
  506.  
  507.                     Sends  a string of characters  and checks if  a hot key
  508.                     was  pressed  during  the transmission.  If  no  key is
  509.                     pressed when the  string was sent, Easy-Door  will wait
  510.                     for one of the characters in the hot keys list.
  511.  
  512.                     Example:
  513.  
  514.                     S$="M=Return to main menu   Q=Quit this DOOR"
  515.                     CALL SendString (S$, "MQ", K$)
  516.                     PRINT "The user has pressed the "+K$+" key."
  517.  
  518.             SpecialCLS
  519.  
  520.                     Clears the screen and redraws the bottom status bar.
  521.  
  522.                     Example:
  523.  
  524.                     CALL SpecialCLS ' Clear the screen and redraw the
  525.                                       status bar.
  526.  
  527.  
  528.             Timeleft (Minleft%)
  529.  
  530.                     Returns the number of minutes left the user has
  531.  
  532.                     Example:
  533.  
  534.                     CALL Timeleft (Time%)    ' Ask the time left.
  535.                     TimeLeft$ = STR$ (Time%) ' Put the value in a string
  536.                     CALL Send ("Timeleft = " + Timeleft$ + " minutes.")
  537.  
  538.  
  539.                                       *** END ***
  540.  
  541.  
  542.                Thank  you for using the Easy-Door library. Hope it's useful
  543.             to you like  it's to me. You  don't know, maybe  you'll make  a
  544.             shareware door with  Easy-Door. So,  please register  the Easy-
  545.             Door library! 
  546.  
  547.                                              The author, 
  548.                                                          Martin Bouchard
  549.  
  550.